home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 November: Tool Chest / Dev.CD Nov 00 TC Disk 1.toast / Sample Code / Graphics 3D / SetupGL / SetupGL.h < prev   
Encoding:
Text File  |  2000-09-28  |  9.3 KB  |  180 lines  |  [TEXT/CWIE]
  1. /*
  2.     File:        SetupGL.h
  3.  
  4.     Contains:    Functions to enable build and destory a GL fullscreen context
  5.  
  6.     Written by:    Geoff Stahl (ggs)
  7.  
  8.     Copyright:    Copyright © 1999 Apple Computer, Inc., All Rights Reserved
  9.  
  10.     Change History (most recent first):
  11.  
  12.          <7>     3/21/00    ggs     Added windowed mode and clean up various implementation details
  13.          <6>     1/26/00    ggs     Add fade code back in, ensure NULL pointer/context/drawable
  14.                                     checks are in, add Preflight
  15.          <5>     1/24/00    ggs     Added get device num and get gdhandle from point routines, add
  16.                                     support for compiling from C++
  17.          <4>    12/18/99    ggs     Fix headers
  18.          <3>    11/28/99    ggs     Split out DSp and error handling.  Added texture memory
  19.                                     considerations, assume VRAM is required if other than zero
  20.          <3>    11/12/99    ggs     add pixel format and freq return
  21.          <2>    11/12/99    ggs     1.0 Interface complete
  22.          <1>    11/11/99    ggs     Initial Add
  23.  
  24.     Disclaimer:    IMPORTANT:  This Apple software is supplied to you by Apple Computer, Inc.
  25.                 ("Apple") in consideration of your agreement to the following terms, and your
  26.                 use, installation, modification or redistribution of this Apple software
  27.                 constitutes acceptance of these terms.  If you do not agree with these terms,
  28.                 please do not use, install, modify or redistribute this Apple software.
  29.  
  30.                 In consideration of your agreement to abide by the following terms, and subject
  31.                 to these terms, Apple grants you a personal, non-exclusive license, under Apple’s
  32.                 copyrights in this original Apple software (the "Apple Software"), to use,
  33.                 reproduce, modify and redistribute the Apple Software, with or without
  34.                 modifications, in source and/or binary forms; provided that if you redistribute
  35.                 the Apple Software in its entirety and without modifications, you must retain
  36.                 this notice and the following text and disclaimers in all such redistributions of
  37.                 the Apple Software.  Neither the name, trademarks, service marks or logos of
  38.                 Apple Computer, Inc. may be used to endorse or promote products derived from the
  39.                 Apple Software without specific prior written permission from Apple.  Except as
  40.                 expressly stated in this notice, no other rights or licenses, express or implied,
  41.                 are granted by Apple herein, including but not limited to any patent rights that
  42.                 may be infringed by your derivative works or by other works in which the Apple
  43.                 Software may be incorporated.
  44.  
  45.                 The Apple Software is provided by Apple on an "AS IS" basis.  APPLE MAKES NO
  46.                 WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED
  47.                 WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  48.                 PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN
  49.                 COMBINATION WITH YOUR PRODUCTS.
  50.  
  51.                 IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR
  52.                 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  53.                 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  54.                 ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION
  55.                 OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, TORT
  56.                 (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN
  57.                 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  58.  
  59. */
  60.  
  61.  
  62. // Usage notes: 
  63.  
  64.  
  65.  
  66. // include control --------------------------------------------------
  67.  
  68. #ifndef SetupGL_h
  69. #define SetupGL_h
  70.  
  71.  
  72. // includes ---------------------------------------------------------
  73.  
  74. #include <DrawSprocket.h>
  75.  
  76. #include <agl.h>
  77.  
  78. #ifdef __cplusplus
  79. extern "C" {
  80. #endif
  81.  
  82. // structures (public) -----------------------------------------------
  83.  
  84. struct structGLInfo // storage for setup info
  85. {
  86.     short width;                // input: width of drawable (screen width in full screen mode), return: actual width allocated
  87.     short height;                // input: height of drawable (screen height in full screen mode), return: actual height allocated
  88.     Boolean fSizeMust;            // input: dspContext must be requested display size (ignored in window mode)
  89.                                     // if fSizeMust display size will not be stepped down to try to find a match, 
  90.                                     // if display is stepped down aspect ratio will be maintained for returned size
  91.     short pixelDepth;            // input: requested pixel depth
  92.     Boolean fDepthMust;            // input: pixel depth must be set (if false then current depth will be used if able)
  93.     Boolean fFullscreen;        // input: use DSp to get fullscreen? (or find full screen renderer)
  94.                                     // if fFullscreen, will search for full screen renderers first then use DSp for others
  95.                                     //  unless a device is specified, in which case we will try there first
  96.     Boolean fAcceleratedMust;     // input: must renderer be accelerated?
  97.     GLint aglAttributes[64];     // input: pixel format attributes always required (reset to what was actually allocated)
  98.     long VRAM;                    // input: minimum VRAM; output: actual (if successful otherwise input)
  99.     long textureRAM;            // input: amount of texture RAM required on card; output: same (used in allcoation to ensure enough texture
  100.     AGLPixelFormat    fmt;        // input: none; output pixel format...
  101.     int freq;                    // input: frequency request for display; output: actual
  102. };
  103. typedef struct structGLInfo structGLInfo;
  104. typedef struct structGLInfo * pstructGLInfo;
  105.  
  106. // structure fro creating a context from a window
  107. struct structGLWindowInfo // storage for setup info
  108. {
  109.     Boolean fAcceleratedMust;     // input: must renderer be accelerated?
  110.     GLint aglAttributes[64];     // input: pixel format attributes always required (reset to what was actually allocated)
  111.     long VRAM;                    // input: minimum VRAM; output: actual (if successful otherwise input)
  112.     long textureRAM;            // input: amount of texture RAM required on card; output: same (used in allcoation to ensure enough texture
  113.     AGLPixelFormat    fmt;        // input: none; output pixel format...
  114.     Boolean fDraggable;            // input: is window going to be dragable, 
  115.                                 //        if so renderer check (accel, VRAM, textureRAM) will look at all renderers vice just the current one
  116.                                 //        if window is not dragable renderer check will either check the single device or short 
  117.                                 //            circuit to software if window spans multiple devices 
  118.                                 //        software renderer is consider to have unlimited VRAM, unlimited textureRAM and to not be accelerated
  119. };
  120. typedef struct structGLWindowInfo structGLWindowInfo;
  121. typedef struct structGLWindowInfo * pstructGLWindowInfo;
  122.  
  123. // public function declarations -------------------------------------
  124.  
  125. // Checks for presense of OpenGL and DSp (if required)
  126. // Inputs: checkFullscreen: true if one wants to run fullscreen (which requires DrwSprocket currently)
  127. // Ouputs: true if OpenGL is installed (and DrawSprocket if checkFullscreen is true
  128. Boolean PreflightGL (Boolean checkFullscreen);
  129.  
  130. // Takes device # and geometry request and tries to build best context and drawable
  131. //     If requested device does not work, will start at first device and walk down devices 
  132. //     looking for first one that satisfies requirments
  133. //  Devices are numbered in order that DMGetFirstScreenDevice/DMGetNextScreenDevice returns, 
  134. //     fullscreen devices are numbered after this, but they will be searched first if fFullscreen == true,
  135. //     they will not be searched in the non-fullscreen case
  136.  
  137. // Inputs:     *pnumDevice: -1: main device, 0: any device, other #: attempt that device first, then any device
  138. //            *pcontextInfo: request and requirements for cotext and drawable
  139.  
  140. // Outputs: *paglDraw, *paglContext and *pdspContext as allocated
  141. //            *pnumDevice to device number in list that was used 
  142. //            *pcontextInfo:  allocated parameters
  143.  
  144. // If fail to build context: paglDraw, paglContext and pdspContext will be NULL
  145. // If fatal error: will return error and paglDraw, paglContext and pdspContext will be NULL
  146. // Note: Errors can be generated internally when a specific device fails, this is normal and these
  147. //          will not be returned is a subsequent device succeeds
  148. OSStatus BuildGL (AGLDrawable* paglDraw, AGLContext* paglContext, DSpContextReference* pdspContext, 
  149.                   short* pnumDevice, pstructGLInfo pcontextInfo);
  150.                   
  151. // Destroys drawable and context
  152. // Ouputs: *paglDraw, *paglContext and *pdspContext should be 0 on exit
  153. OSStatus DestroyGL (AGLDrawable* paglDraw, AGLContext* paglContext, DSpContextReference* pdspContext, pstructGLInfo pcontextInfo);
  154.  
  155.  
  156. // same as above except that it takes a window as input and attempts to build requested conext on that
  157. OSStatus BuildGLFromWindow (AGLDrawable aglDraw, AGLContext* paglContext, pstructGLWindowInfo pcontextInfo);
  158.  
  159. // same as above but destorys a context that was associated with an existing window, window is left intacted
  160. OSStatus DestroyGLFromWindow (AGLContext* paglContext, pstructGLWindowInfo pcontextInfo);
  161.  
  162.  
  163. // Pauses gl to allow toolbox drawing
  164. OSStatus PauseGL (AGLContext aglContext);
  165.  
  166. // resumes gl to allow gl drawing
  167. OSStatus ResumeGL (AGLDrawable aglDraw, AGLContext aglContext);
  168.  
  169. short FindGDHandleFromRect (Rect * pRect, GDHandle * phgdOnThisDevice);
  170.  
  171. short FindGDHandleFromWindow (WindowPtr pWindow, GDHandle * phgdOnThisDevice);
  172.  
  173. // returns the number of the device that the rect is mostly is on (i.e., where it is numerically in the search order)
  174. short FindDeviceNumFromRect (Rect * rect);
  175.  
  176. #ifdef __cplusplus
  177. }
  178. #endif
  179.  
  180. #endif // SetupGL_h